% \documentclass[preprint]{aastex}
%\documentclass{article}
\documentclass{report}
\usepackage{fullpage}
\usepackage{graphicx}
\usepackage{subfigure}
\usepackage{rotating}
\usepackage{lscape}
\usepackage{natbib}
\usepackage{hyperref}
\pagestyle{empty}
\usepackage{aas_macros}
\usepackage{longtable}
\usepackage{amsmath}
\bibliographystyle{apj}

\hypersetup{
  bookmarks=true,         % show bookmarks bar?
  unicode=false,          % non-Latin characters in Acrobat's bookmarks
  pdftoolbar=true,        % show Acrobat's toolbar?
  pdfmenubar=true,        % show Acrobat's menu?
  pdffitwindow=true,      % page fit to window when opened
  pdftitle={Stellar Locus Regression Manual},    % title
  pdfauthor={F. William High},     % author
  pdfsubject={astronomical calibration},   % subject of the document
  pdfnewwindow=true,      % links in new window
  pdfkeywords={astronomy, colors, calibration, stars}, % list of keywords
  colorlinks=true,        % false: boxed links; true: colored links
  linkcolor=red,          % color of internal links
  citecolor=red,          % color of links to bibliography
  filecolor=magenta,      % color of file links
  urlcolor=blue           % color of external links
}

\newcommand{\zptcolor}{\boldsymbol{\kappa}}
%\newcommand{\atmextcolor}{\mathcal{E}^{\text{A}}}
%\newcommand{\galextcolor}{\mathcal{E}^{\text{G}}}
\newcommand{\atmextcolor}{\boldsymbol{E}^{\text{A}}}
\newcommand{\galextcolor}{\mathcal{E}^{\text{G}}}
%\newcommand{\colorvec}{\mathcal{C}}
\newcommand{\colorvec}{\boldsymbol{c}}
\newcommand{\colorconst}{\boldsymbol{\gamma}}
%\newcommand{\colormatrix}{\mathcal{M}}
\newcommand{\colormatrix}{\mathbf{B}}
\newcommand{\identity}{\boldsymbol{1}}
\newcommand{\colorairmassmatrix}{\mathbf{T}}
\newcommand{\sdss}{SDSS}
\newcommand{\slr}{SLR} 
\newcommand{\imacs}{IMACS}
\newcommand{\ldss}{LDSS3}
\newcommand{\tmass}{2MASS}
\newcommand{\reflex}{REFLEX}
\newcommand{\gof}{GOF} 
\newcommand{\ndeg}{{$^{\circ}$}}
\newcommand{\metal}{[\text{Fe}/\text{H}]}

\begin{document}

\title{Stellar Locus Regression\\User Manual}

\author{F.\ William High}

\date{\today}


\pagenumbering{roman}

%% Personalized Title Page
\begin{titlepage}
\begin{minipage}{\textwidth}
\begin{center}
\Huge
Stellar Locus Regression\\User Manual\\
\vspace{3cm}
\Large
F.~William High\\
\vspace{3cm}
\large
University of Chicago\\Department of Astronomy and Astrophysics\\Kavli
Institute for Cosmological Physics\\933 East 56th Street\\Chicago, IL 60637\\
\href{mailto:fwhigh@kicp.uchicago.edu}{fwhigh@kicp.uchicago.edu}\\
\url{http://kicp.uchicago.edu/~fwhigh/}
\end{center}
\end{minipage}
\end{titlepage}

\begin{minipage}{\textwidth}

\section*{}

Copyright \copyright{}  2009  Fredrick William High.\\
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".

% \section*{Acknowledgements}

% Stellar Locus Regression was developed with Christopher Stubbs, Armin
% Rest, Brian Stalder, and Pete Challis at Harvard University.  Thanks
% to Patrick Kelly, for useful conversations.

\end{minipage}

% \begin{abstract}

%   Stellar Locus Regression (\slr) is an algorithm that takes
%   uncalibrated astronomical magnitudes of stars from any field and
%   calibrates the colors, which are magnitude differences, without the
%   traditional use of standard stars. \slr\ exploits the fact that the
%   majority of stars in the sky have colors that occupy a well defined,
%   nearly one-dimensional region in hyperdimensional color-color
%   space. This is called the stellar locus. \slr\ regresses raw colors
%   to a standard stellar locus, delivering best-fit calibration terms,
%   which can be applied to the other point- and extended-sources in the
%   catalog. \slr\ can be performed on as few as 7 stars and in fields of
%   view down to 8 arcminutes. \slr\ can be performed in real time,
%   during observation.

%   This is a short guide to installing and running the stellar locus
%   regression (\slr) on example and user data.  A more detailed
%   description of the \slr\ alogrithm and verifcation of its
%   effectiveness is available, see \citet{bib:slr}.  Since this is an
%   evolving code, this guide will supercede the paper if there are
%   differences.

% \end{abstract}


\tableofcontents
\pagenumbering{arabic}
\setcounter{page}{1}

\input{preliminaries}

\chapter{Introduction}

Stellar Locus Regression (\slr) is a method of directly adjusting the
instrumental broadband optical colors of stars to bring them into
accord with a universal stellar color-color locus, producing
accurately calibrated colors for both stars and galaxies.  

We offer an implementation of \slr\ in the Interactive Data Language
(IDL).  This manual is a guide on getting, installing, and running our
public IDL code.

The peer-reviewed paper of \citet{bib:slr} initially outlined the
broad ideas behind the technique, established the mathematical
formalism, and presented the first tests of the technique.  We expect
\slr\ to have even broader applicability to astronomy than we
envisaged in that article.

\section{What \slr\ Is}

At it's core, \slr\ simply fits instrumental colors of stars to a
standard line, delivering calibration parameters that can then be
applied to all objects in the field.

Instrumental colors are differences in instrumental magnitudes.
Instrumental magnitudes are the direct product of measuring photometry
in bias-subtracted, flat-fielded images.  Source Extractor
\citep{bib:sextractor} is the common tool for measuring instrumental
magnitudes.  The distinctive stellar locus is seen immediately in
instrumental color-color plots of stars in the field.  The red points
in the top panels of Figure \ref{fig:example} are a real example of
this.

\begin{figure}
% \epsscale{0.75}
  \center
  \includegraphics[scale=0.6]{fig/illus_sptcl2332_5051_locus_threepanel.eps}
  \caption{ An illustration of Stellar Locus Regression (\slr).
    Colors are plotted on the SDSS photometric system. All panels show
    the standard stellar locus (black line and gray density contours),
    reproduced from \citet{bib:covey}.  Red points are stellar colors
    obtained from a Source Extractor analysis of flat-fielded Magellan
    $6.5\,\mathrm{m}$ IMACS images.  {\it Top panels:} The
    instrumental IMACS colors are plotted, with a clear mismatch
    between them and the standard locus. {\it Middle panels:} \slr\ is
    performed with only a common translation vector applied to the
    instrumental colors.  Note the color-dependent discrepancies in
    the upper right portions of the central panels.  {\it Bottom
      panels:} Color terms are measured from a single, separate
    observation of a field containing standard stars. Fixing these
    color terms, a new best-fit translation is determined, which
    brings the observed colors onto the \sdss-calibrated color system,
    as defined by the stellar locus.  This \slr\ analysis, when the
    corrections are then applied to all objects in the photometric
    catalog, allows us to rapidly obtain highly accurate colors on the
    SDSS system, directly from flat-fielded data, with a single
    correction step that accounts for atmospheric extinction, Galactic
    extinction and instrumental response differences.}
 \label{fig:example}
\end{figure}
% \epsscale{1.0}

The instrumental stellar locus closely resembles the calibrated
stellar locus, shown with the heavy line and gray density contours in
Figure \ref{fig:example}.  If we align the two loci with simple
shifts, we arrive at the middle panels of Figure \ref{fig:example}.
The two agree somewhat, although we see a systematic difference.  This
difference arises from using a different instrument (Magellan in
Chile) than that used to make the standard stellar locus (Sloan
Digital Sky Survey telescope in New Mexico).  We measure and apply the
usual instrumental color terms, re-measure the shift, and produce a
stellar locus that matches the standard one nearly perfectly.  This is
shown in the bottom panels of Figure \ref{fig:example}.

The product is a color calibration that can be applied to all objects
in the same field where the calibrator stars appeared.  The \slr\
color calibration is achieved without first establishing individual
zeropoints for each passband, can be performed in real-time at the
telescope, and makes use of the stars from any field---they need not
be standards.  \citet{bib:slr} demonstrated how \slr\ naturally makes
one wholesale correction for differences in instrumental response, for
atmospheric transparency, for atmospheric extinction, and for Galactic
extinction.  

This all assumes that the standard locus is universal.  We explored
the extent to which this is true in \citet{bib:slr}, both in theory
and in practice.  We found that \slr\ calibrations are repeatable with
sub-percent systematic color uncertainty, that \slr\ re-calibrations
of \sdss\ data are directly sensitive to reddening by Galactic dust at
the 2\% level for the fields we looked at, and \slr\ calibrations of
red cluster galaxy colors were sufficiently accurate to deliver
cluster photometric redshifts with 0.6\% systematic uncertainty (which
we found to be consistent with 2\% color errors).

\slr\ is a simple and fundamentally different way of calibrating
photometry.  It works, and it works well.

Figure \ref{fig:algorithm} schematically outlines how \slr\ fits into
a typical calibration scheme.  The core IDL tools we have developed
are available at \url{http://stellar-locus-regression.googlecode.com},
and this manual serves as a guide to that particular code.

\begin{figure}
\center
\includegraphics[scale=0.9]{fig/slr_algorithm.eps}
\caption{ \slr\ flow chart for calibrating colors.  The hashed region
  denotes parts of the algorithm that are unique to \slr, while the
  non-shaded region shows steps that are more traditional.  The dotted
  region denotes the color term estimation routine, which need only be
  performed once per detector. }
\label{fig:algorithm}
\end{figure}

\section{Equation Being Solved}

\slr\ solves the equation
\begin{equation}
  \label{eqn:transform}
  \colorvec = \zptcolor + (\identity + \colormatrix)(\colorvec_0-\colorconst),
\end{equation}
where $\colorvec$ is the vector of colors being calibrated,
$\zptcolor$ is the vector of zeropoint differences for each color,
$\identity$ is the identity matrix, $\colormatrix$ is the matrix of
color terms, $\colorvec_0$ is color ``truth'', and $\colorconst$ is a
vector of constants.

This differs from Equation (1) of \citet{bib:slr} only by the
inclusion of the color-constant vector $\colorconst$ on the right-hand
side.  The effect of the color constants is to bring the color pivot
point to roughly the mean of the stellar locus, so that the
$\zptcolor$ vector is approximately equal for zero-value color terms
as for nonzero color terms.  If $\colorconst$ is set to zero, then
this equation reduces to Equation (1) of \citet{bib:slr}.

\section{Accepted Passbands}

As of now, this implementation will accept and calibrate colors and
magnitudes taken from the filterset $ugrizUBVRIJHK$.  It will output
calibrations of $ugriz$ colors and mags in the AB system, and
$UBVRIJHK$ in Vega.  Colors that are hybrids of these 2 filter sets,
e.g., $i-J$, will therefore be $i$ AB minus $J$ Vega.

The list of accepted passbands is determined only by the filters in
which the standard stellar locus of \citet{bib:covey} is defined.  The
list is therefore easy to expand as long as the standard locus shape
in the new filterset is known.  The current implementation does not
(yet) accept an arbitrary input stellar locus line.



\chapter{Quick Start}


\begin{enumerate}
\item \href{http://stellar-locus-regression.googlecode.com}{Download}
  the \slr\ code and unpack it in a directory of your choosing,
  $<$install-dir$>$.
\item Install and set up the \href{http://idlastro.gsfc.nasa.gov}{Goddard
    astronomy} IDL libraries,
  \href{http://www.astro.princeton.edu/~schlegel/code.html}{idlutils},
  and the \href{http://www.physics.wisc.edu/~craigm/idl}{Markwardt IDL
    libraries}.
%\item {\bf Optional:}
%  \href{http://astro.berkeley.edu/~marc/dust}{Install and set up} the
%  \citet{bib:sfd} $E(B-V)$ dust maps and IDL utilities.
\item
  \href{http://www.cfa.harvard.edu/~kcovey/research/medianlocus.tbl}{Download}
  the stellar locus data of \citet{bib:covey} and put them in a
  directory $<$data-dir$>$/covey.
\item Set environment variables (here in tcsh):
\begin{verbatim}
% setenv SLR_INSTALL <install-dir>/slr-v*
% setenv SLR_DATA <data-dir>
% setenv IDL_PATH {$IDL_PATH}:+$SLR_INSTALL/pro
% setenv PATH {$PATH}:$SLR_INSTALL/bin
\end{verbatim}
  where the version number v*\ corresponds to whatever you
  downloaded in step 1.
\item Verify your installation (see \S\ref{sec:verify}):
\begin{verbatim}
% idl
IDL> slr_docs
IDL> exit
% cd $SLR_INSTALL/example_data
% slr.csh low_reddening.ctab low_reddening.slr.ctab
% slr.csh high_reddening.ctab high_reddening.slr.ctab
% idl
IDL> slr_demo
IDL> exit
% cat low_reddening.slr.ctab
% cat low_reddening.slr
% cat high_reddening.slr.ctab
% cat high_reddening.slr
\end{verbatim}
\end{enumerate}


\chapter{Installation}

\section{Download}

First, go get the latest download at
\url{http://stellar-locus-regression.googlecode.com}. Untar it with
\begin{verbatim}
tar xzvf slr-v*.tar.gz
\end{verbatim}
where the version number v*\ corresponds to whatever you downloaded.
Put the package in some directory $<$install-dir$>$. This can be
/usr/local/idllibraries or \$HOME or whatever you prefer. The package
root directory will then be $<$install-dir$>$/slr-v*.


\section{IDL Libraries}

You'll need these idl libraries:

\begin{enumerate}
\item idlutils from
  \url{http://www.astro.princeton.edu/~schlegel/code.html}.  Any
  installation procedure will do, but you probably want the latest
  idlutils tar file, e.g.\ idlutils-v5\_3\_0.tar.
\item {\it The latest} Goddard astro libraries from
  \url{http://idlastro.gsfc.nasa.gov}.  Note that idlutils comes with
  an old version of the Goddard libraries that is {\it incompatible
    with this implementation of SLR}.  Get the latest one.
\item Markwardt libraries from
  \url{http://www.physics.wisc.edu/~craigm/idl}.  You want
  cmtotal.tar.gz.
\end{enumerate}

Put them in your typical IDL directory. For example, use a directory
you can remember $<$pro-dir$>$, like /usr/local/idllibraries.

Don't forget to add them to your IDL\_PATH with shell startup file
entries similar to:
\begin{verbatim}
% export IDL_PATH=$IDL_PATH:+<pro-dir>/idlutils:+<pro-dir>/markwardt
\end{verbatim}
in bash or
\begin{verbatim}
% setenv IDL_PATH {$IDL_PATH}:+<pro-dir>/idlutils:+<pro-dir>/markwardt
\end{verbatim}
in tcsh.

Of course all of this assumes you have properly initialized the
IDL\_PATH, for example in tcsh:
\begin{verbatim}
% setenv IDL_BIN /usr/local/itt/idl/bin
% source $IDL_BIN/idl_setup
% setenv IDL_PATH <IDL_DEFAULT>
\end{verbatim}

% \section{Optional: Galactic Dust Maps}

% Some optional functionality of \slr\ requires the dust maps of
% \citet{bib:sfd}.  To enable these functions, the maps need to be
% located in \$DUST\_DIR/maps. Here's how to set this up:

% Go to \url{http://astro.berkeley.edu/~marc/dust} to get the dust maps
% and IDL code.

% Follow their install instructions. You only need the high resolution
% 4096 $E(B-V)$ maps, both the north and south Galactic planes (NGP and
% SGP). Put them in some directory, for example
% $<$install-dir$>$/slr-v2.2/example\_data/sfd/maps. Make sure the top
% directory is maps and not map. Put the SFD IDL code in some
% $<$pro-dir$>$ and add to IDL\_PATH.

% As instructed at the website, set the DUST\_DIR environment
% variable. If you used our suggestion, then you would issue
% \begin{verbatim}
% % setenv DUST_DIR <install-dir>/slr-v2.1/example_data/sfd
% \end{verbatim}

% The directory \$DUST\_DIR/maps must exist and contain the E(B-V)
% dust maps.

\section{Standard Stellar Locus}

\slr\ gets the standard stellar locus data from the directory
\$SLR\_DATA/covey.

Go get Kevin Covey's stellar locus data, which he makes available on
his own website. You'll need 
%% the stellar data\\
%% \url{http://www.cfa.harvard.edu/~kcovey/research/superclean.fits}\\
%% and 
the median locus line data:\\
\url{http://www.cfa.harvard.edu/~kcovey/research/medianlocus.tbl}\\
Put them in some directory $<$data-dir$>$/covey. We suggest putting
them in the $<$install-dir$>$/example\_data/covey subdirectory of
your installation. Set SLR\_DATA. If you used our suggestion, then
you would issue

\begin{verbatim}
% setenv SLR_DATA <install-dir>/example_data
\end{verbatim}

The directory \$SLR\_DATA/covey must exist and contain
medianlocus.tbl and superclean.fits.

\section{Environment Variables}

Now set some environment variables in your cshrc or bashrc file. Remember to insert the appropriate directories. Example is for tcsh:
\begin{verbatim}
% setenv SLR_INSTALL <install-dir>/slr-v1.0
% setenv SLR_DATA <data-dir>
% setenv IDL_PATH {$IDL_PATH}:+$SLR_INSTALL/pro
% setenv PATH {$PATH}:SLR_INSTALL/bin
\end{verbatim}

We've used the example directories mentioned in this install
file. This should let the demo (see below) work properly. If you made
different choices, you must make sure these environment variables
reflect them.

\chapter{Usage}
\label{sec:verify}

\section{Verifying Your Installation}

If everything is set up properly, you can run the demo by invoking IDL
and running:
\begin{verbatim}
% cd $SLR_INSTALL/example_data
% idl
IDL> slr_demo
\end{verbatim}

The first time you run it, it will take some time (it's reformatting
the data to an optimal, IDL-friendly format). It will be faster the
second time.

The demo will run \slr\ on the example Sloan Digital Sky Survey data
that comes with your installation. You should see plots of the stellar
locus (you must hit enter to continue), a visualization of the
numerical regression, and results for best-fit parameters printed to
screen.


\section{Running slr.csh Using Example Data}

Go to the directory \$SLR\_INSTALL/example\_data, then issue at
the commandline (you have to be in same directory as your input file):
\begin{verbatim}
% cd $SLR_INSTALL/example_data
% slr.csh low_reddening.ctab low_reddening.slr.ctab
\end{verbatim}

This will run \slr\ on the example colortable we provided (first
argument), and output \slr\ calibrations to another colortable (second
argument). The output colortable is equal to the input colortable but
with the additional appended columns GR, RI, etc, which are the
calibrated colors g - r, r - i. Estimated color errors, with bootstrap
errors added in quadrature, are also output.

Browse the output table of calibrated colors, and the log file that
\slr\ generates, in this case lowext\_stars3\_fwhigh.slr. The latter
contains the color calibration parameters with bootstrap errors.
\begin{verbatim}
% cat low_reddening.slr.ctab
% cat low_reddening.slr
\end{verbatim}

If that works then you should also be able to run
\begin{verbatim}
% cd $SLR_INSTALL/example_data
% slr.csh high_reddening.ctab high_reddening.slr.ctab
\end{verbatim}
Browse the output:
\begin{verbatim}
% cat high_reddening.slr.ctab
% cat high_reddening.slr
\end{verbatim}


\section{Running slr.csh with Your Own Data}

To run \slr\ on your own data, issue the command (again, in the same
directory as your input file):
\begin{verbatim}
% slr.csh input.ctab output.slr.ctab <config-file>
\end{verbatim}
The configuration file can optionally be specified.  If none is given,
then the default file is used, \$SLR\_INSTALL/config/default.config.

This has the same output as the previous section.  See
\S\ref{sec:colortable} for requirements on acceptable input colortable
formatting.

The code outputs a new colortable with calibrated colors and
optionally magnitudes, with errors.  The output filename is the input
filename with the string ``slr.ctab'' appended.  If the input filename
had ``.ctab'' as the suffix, then this suffix is first removed in
order to avoid duplication.  The \slr\ log file is the input
colortable file name with ``.slr'' appended.  Again, ``.ctab'' is
first removed if is the input file's suffix.


\section{Writing Wrappers}


At its core, \slr\ simply fits $ugrizUBVRIJHK$ colors to a standard
locus. This is done with slr\_pipe.pro.  \slr\ doesn't care where the
input magnitudes came from, nor whether they were previously
calibrated fully, partially, or at all.  \slr\ only knows how to make
the input stellar locus look like the standard locus, thereby
producing calibrated colors.

\subsection{slr\_pipe.pro}

But the real power of \slr\ comes from writing wrappers to
slr\_pipe.pro.  For example, if you have uncalibrated $griz$
magnitudes, with 2MASS $J$-band data for a subset of your stars, then
you can make a wrapper that calls slr\_pipe three times:
\begin{enumerate}
\item Calibrate only the colors $(g-r,r-i,i-z)$.  This produces the
  vector of color translations
  $\zptcolor=(\kappa_{gr},\kappa_{ri},\kappa_{iz})$.
\item Then calibrate only the colors $(i-z,z-J)$, but pass the
  calibration parameter $\kappa_{iz}$ as an input and leave it fixed
  during the fit. This produces $\kappa_{zJ}$, which happens to be
  equal to your $z$-band zeropoint (which includes atmospheric
  extinction, Galactic extinction, the instrumental zeropoint, and so
  on).
\item Run it one more time, leaving $\zptcolor$ fixed to the values
  you just measured, to produce a catalog that contains the calibrated
  colors $(g-r,r-i,i-z)$.
\end{enumerate}
All three of these tasks are within the scope of slr\_pipe, even
though they have conceptually different results.

This is made possible by passing parameters on the IDL commandline.
The best fit $\zptcolor$ can be access via the IDL keyword kappa\_out,
and its error via kappaerr\_out.  These can then be accessed then
passed to the next call of slr\_pipe using syntax like
\begin{verbatim}
IDL> slr_pipe,infile='low_reddening.ctab',$
IDL>          outfile='low_reddening.slr.ctab',$
IDL>          kappa_out=low_kappa, kapperr_out=low_kappa_err
IDL> slr_pipe,infile='low_reddening.ctab',$
IDL>          outfile='low_reddening.slr.ctab',$
IDL>          kappa_guess=low_kappa, kappa_guess_err=low_kappa_err, $
IDL>          nbootstrap=0
\end{verbatim}
In this example we've run \slr\ twice, but the second time we changed
the initial guess for $\zptcolor$ used during the regression.  We also
decided not to do the bootstrap the second time, choosing instead to
use the first bootstrap errors as our estimates for errors on the new
$\zptcolor$.

This works because any parameter that appears in the configuration
file (\S\ref{sec:config}) can be passed to slr\_pipe, verbatim.
Commandline parameters overwrite those parsed from the configuration
file.

Wrapping around slr\_pipe lets you loop over lots of data and/or run
sophisticated calibrations, like the $grizJ$ scheme described above.



\chapter{Pre-Processing Your Data}
\label{sec:prepost}

Before you run \slr, you'll have to have multiband observations of a
given field in hand.  All images must be bias-subtracted and
flat-fielded, including dome flats, fringe corrections, and ideally
illumination corrections as well.  You'll then run SExtractor or the
equivalent to detect objects in each band, and identify unique stars,
galaxies, and other objects between all bands.  The result will be a
list of instrumental magnitudes for each object in the field in each
band.  You can subtract instrumental magnitudes to arrive at
intstrumental colors.

If you want to standardize your colors to a system using a different
instrument than that originally used to establish the standard, then
you'll probably have to measure color terms, as described in
\S\ref{sec:colorterms}.

The final steps are to format your multi-band instrumental catalog
into an \slr-readable colortable \S\ref{sec:colortable}, and to tell
\slr\ about your color terms using the config files
(\S\ref{sec:config}-\ref{sec:colorterms}).  You're now ready to run
\slr.

Of course, you can also run \slr\ on photometry that has already been
calibrated to any degree.  When running \slr\ in this case, it will
give you new calibrations such that the colors resemble the standard
locus line as well as possible.






\chapter{The Colortable}
\label{sec:colortable}

SLR reads data from and outputs results to what we call {\it
  colortables}.  These are simple ascii files with a single header
that starts with \verb|#| and one row of data per object.  The header
values are columns names, and each row corresponds to one object.
Here's a simple (truncated) example:
\begin{verbatim}
# ID        RA       Dec type tmixed       g  g_err       r  r_err ...
   0 254.00649  34.33696    1      0  20.672  0.025  19.795  0.018 ...
   1 254.05269  34.36260    1      0  16.426  0.004  15.849  0.004 ...
   2 254.02026  34.34031    1      0  23.670  0.283  21.607  0.072 ...
   3 254.00436  34.36294    1      0  20.381  0.021  19.012  0.011 ...
   4 254.02655  34.34580    1      0  18.203  0.006  17.059  0.005 ...
...
\end{verbatim}
The ellipses ... here mean there can be additional columns and rows.

The columns can be any fixed width, but they must be fixed.  The
header strings however need not be fixed width.  Empty or erroneous
data must generically be represented by the character ``\verb|-|''
(dash).

While there is a minimal subset of columns that must be present for
SLR to work properly, it is acceptable for there to be extra columns
that the code doesn't formally recognize or use.  This way you can
carry extra information in the colortable, such as \verb|ID| in the
example above.

Table \ref{tab:colortable} lists the columns that are recognized and
used by the SLR code.

\begin{center}
\begin{longtable}{lllcp{3in}}
\caption[Colortable columns.]{Colortable columns.}
\label{tab:colortable} \\
  \hline \hline \\[-2ex]
  \multicolumn{1}{c}{Column name} &
  \multicolumn{1}{c}{Type} &
  \multicolumn{1}{c}{Unit} &
  \multicolumn{1}{c}{Required?} &
  \multicolumn{1}{c}{Description} \\[0.5ex] \hline
\endfirsthead
\multicolumn{5}{c}{{\tablename} \thetable{} continued: Colortable columns.} \\[0.5ex]
  \hline \hline \\[-2ex]
  \multicolumn{1}{c}{Column name} &
  \multicolumn{1}{c}{Type} &
  \multicolumn{1}{c}{Unit} &
  \multicolumn{1}{c}{Required?} &
  \multicolumn{1}{c}{Description} 
\\[0.5ex] \hline
  \\[-1.8ex]
\endhead
\multicolumn{5}{l}{{{\it Continued on next page}\ldots}} \\
\endfoot
  \\[-1.8ex] \hline \hline
\endlastfoot
\verb|ID| & {\it string} & J2000 $\deg$ & Yes & Object identifier. \\
\verb|RA| & {\it float} & J2000 $\deg$ & Yes & Right ascension. \\
\verb|Dec| & {\it float} & J2000 $\deg$ & Yes & Declination. \\
\verb|type| & {\it integer} & & Yes & $1=\textrm{star}$. Only stars should be used. If an object has a different \verb|type|, then the code will ignore it during regression, but will still apply calibrations to all objects when outputting the new colortable. \\
\verb|tmixed| & {\it boolean} & & Yes & Is the \verb|type| ambiguous between the bands? Normally you'll want to run \slr\ on unambiguous stars (\verb|tmixed| $=0$, \verb|type| $=1$). If you are low on stars in your catalog, you can try setting \verb|tmixed| to 1, in which case \slr\ will use all objects of the specified \verb|type|. \\
\verb|U| & {\it float} & mag & UNTESTED & $U$-band magnitude. \\
\verb|U_err| & {\it float} & mag & If \verb|U| present & Uncertainty in Johnson $U$-band magnitude. \\
\verb|B| & {\it float} & mag & UNTESTED & $B$-band magnitude. \\
\verb|B_err| & {\it float} & mag & If \verb|B| present & Uncertainty in Johnson $B$-band magnitude. \\
\verb|V| & {\it float} & mag & UNTESTED & $V$-band magnitude. \\
\verb|V_err| & {\it float} & mag & If \verb|V| present & Uncertainty in Johnson $V$-band magnitude. \\
\verb|R| & {\it float} & mag & UNTESTED & $R$-band magnitude. \\
\verb|R_err| & {\it float} & mag & If \verb|R| present & Uncertainty in Johnson $R$-band magnitude. \\
\verb|I| & {\it float} & mag & UNTESTED & $I$-band magnitude. \\
\verb|I_err| & {\it float} & mag & If \verb|I| present & Uncertainty in Johnson $I$-band magnitude. \\
\verb|u| & {\it float} & mag & UNTESTED & $u$-band magnitude. \\
\verb|u_err| & {\it float} & mag & If \verb|u| present & Uncertainty in SDSS $u$-band magnitude. \\
\verb|g| & {\it float} & mag & No & $g$-band magnitude. \\
\verb|g_err| & {\it float} & mag & If \verb|g| present & Uncertainty in SDSS $g$-band magnitude. \\
\verb|r| & {\it float} & mag & No & $r$-band magnitude. \\
\verb|r_err| & {\it float} & mag & If \verb|r| present & Uncertainty in SDSS $r$-band magnitude. \\
\verb|i| & {\it float} & mag & No & $i$-band magnitude. \\
\verb|i_err| & {\it float} & mag & If \verb|i| present & Uncertainty in SDSS $i$-band magnitude. \\
\verb|z| & {\it float} & mag & No & $z$-band magnitude. \\
\verb|z_err| & {\it float} & mag & If \verb|z| present & Uncertainty in SDSS $z$-band magnitude. \\
\verb|J| & {\it float} & mag & No & $J$-band magnitude. \\
\verb|J_err| & {\it float} & mag & If \verb|J| present & Uncertainty in SDSS $J$-band magnitude. \\
\verb|H| & {\it float} & mag & UNTESTED & $H$-band magnitude. \\
\verb|H_err| & {\it float} & mag & If \verb|H| present & Uncertainty in SDSS $H$-band magnitude. \\
\verb|K| & {\it float} & mag & UNTESTED & $K$-band magnitude. \\
\verb|K_err| & {\it float} & mag & If \verb|K| present & Uncertainty in SDSS $K$-band magnitude. \\
\end{longtable}
\end{center}







\chapter{Configuration Parameters}
\label{sec:config}

SLR reads ascii configuration files that the user can edit.  Comments
can be used with the character \verb|#|.  There must be at least one
space between the parameter name and its value.  Arrays (vectors) are
comma-separated lists; there must be no spaces in such lists.  Each
parameter in the config file must have a corresponding value next to
it.  There can be no empty fields.  All parameters must be present in
the file.

Table \ref{tab:config} describes all configuration paramaters.

\begin{center}
\begin{longtable}{llp{3.5in}}
\caption[Configuration parameters.]{Configuration parameters.}
\label{tab:config} \\
  \hline \hline \\[-2ex]
  \multicolumn{1}{c}{Parameter} &
  \multicolumn{1}{c}{Type} &
  \multicolumn{1}{c}{Description} \\[0.5ex] \hline
\endfirsthead
\multicolumn{3}{c}{{\tablename} \thetable{} continued: Configuration parameters.} \\[0.5ex]
  \hline \hline \\[-2ex]
  \multicolumn{1}{c}{Parameter} &
  \multicolumn{1}{c}{Type} &
  \multicolumn{1}{c}{Description} 
\\[0.5ex] \hline
  \\[-1.8ex]
\endhead
\multicolumn{3}{l}{{{\it Continued on next page}\ldots}} \\
\endfoot
  \\[-1.8ex] \hline \hline
\endlastfoot

~ & ~ & ~ \\ \hline
\multicolumn{3}{c}{Colors to calibrate} \\
\hline ~ & ~ & ~ \\ 

\verb|colors2calibrate| & {\it string array} & Colors to be calibrate by SLR. Comma separated list, eg, \verb|gr,ri,iz,zJ| \\
\verb|kappa_fix| & {\it boolean array} & Fix $\zptcolor$? There must be one entry for each \verb|colors2calibrate|. Can be mixed, eg, \verb|1,0,0,0|. \\
\verb|kappa_guess| & {\it float array} & {\it Initial} values of $\zptcolor$ for the fitting routine whenever \verb|kappa_fix| is 0, or {\it fixed} values of $\mathbf{\kappa}$ whenever \verb|kappa_fix| is 1. In magnitudes. There must be one entry for each \verb|colors2calibrate|. \\
\verb|kappa_guess_err| & {\it float array} & Values of errors for $\zptcolor$, used when not bootstrapping or when only transforming the colors. In magnitudes. \\
\verb|kappa_guess_range| & {\it float array} & Range of acceptable values of $\zptcolor$, used by the fitting routine. In magnitudes. There must be one entry for each \verb|colors2calibrate|. \\

~ & ~ & ~ \\ \hline
\multicolumn{3}{c}{Color terms} \\
\hline ~ & ~ & ~ \\ 

\verb|colorterms| & {\it float array} & Color terms to use. \\
\verb|colorconst| & {\it float array} & Color constants $\colorconst$. The comma separated list of values must correspond to each entry of \verb|colors2calibrate|, and the code will use the appropriate values depending on the specified \verb|colortermbands|. \\
\verb|colortermbands| & {\it string array} & Comma separated list of the bands that use the color terms. Each band here must appear somewhere in \verb|colors2calibrate|, although not all magntiudes in \verb|colors2calibrate| need have a \verb|colortermband|.  See \S\ref{sec:colorterms}.  If {\tt none}, then color terms are not used. \\
\verb|colormult| & {\it string array} & Comma separated list of the colors that multiply the \verb|colorterms|. \\

~ & ~ & ~ \\ \hline
\multicolumn{3}{c}{Controlling the fitter} \\
\hline ~ & ~ & ~ \\ 

\verb|transform_only| & {\it boolean} & If yes, then don't do regression and just calibrate the data using the input $\zptcolor$ and colorterms.  If no, fit for $\zptcolor$ and then perform the color transformation. \\
\verb|weighted_residual| & {\it boolean} & Use the error-weighted residual? \\
\verb|nbootstrap| & {\it integer} & Number of bootstraps to perform. \\

~ & ~ & ~ \\ \hline
\multicolumn{3}{c}{Program behavior} \\
\hline ~ & ~ & ~ \\ 

\verb|force| & {\it boolean} & Force a re-read of ascii data? If not, then read from IDL .sav files if they exist.  \\
\verb|verbose| & {\it integer} & Verbosity level, 0, 1, or 2.  \\
\verb|plot| & {\it boolean} &  \\
\verb|postscript| & {\it boolean} & Write figures to postscript files instead of to screen? \verb|plot| must also be set.  \\
\verb|interactive| & {\it boolean} & Prompt user for response periodically? \\
\verb|animate_regression| & {\it boolean} & Plot each iteration of the fit? \\
\verb|debug| & {\it boolean} & Debug mode? \\
\verb|have_sfd| & {\it boolean} & Are the maps of \citet{bib:sfd} available? Must exist in \$DUST\_DIR/maps. \\


~ & ~ & ~ \\ \hline
\multicolumn{3}{c}{Ouput} \\
\hline ~ & ~ & ~ \\ 

\verb|write_ctab| & {\it boolean} & Write table of calibrated colors (and optionally magnitudes)? \\
\verb|mags2write| & {\it string array} & What bands to write \slr-calibrated magnitudes for, or ``none'' if none. The bands must appear somewhere in \verb|colors2calibrate|. \\
\verb|mag_zeropoints| & {\it string array} & Which elements of $\zptcolor$ are the magnitude zeropoints?  There must be one entry for each \verb|write_mags|.  \\

~ & ~ & ~ \\ \hline
\multicolumn{3}{c}{Conditions on the data} \\
\hline ~ & ~ & ~ \\ 

\verb|type| & {\it integer} & The type identifying stars, which are used in the fit. \\
\verb|tmixed| & {\it boolean} & Whether to allow for point/extended source ambiguity in objects used in the fit. \\
\verb|deredden| & {\it boolean} & Deredden the objects before fitting, using \citet{bib:sfd}? \\
\verb|cutdiskstars| & {\it boolean} & Cut out disk stars with Galactic $|Z|<$ \verb|zeelow| before fitting, using \citet{bib:juric}?  \\
\verb|zeelow| & {\it float} & Lower limit of allowable Galactic scale height $Z$ for stars. Assumes they are main-sequence, and already calibrated. Only used if \verb|cutdiskstars| is set. In parsecs. \\
\verb|beelow| & {\it float} & Lower limit of allowable Galactic latitudes $|b|$, in $\deg$. \\
\verb|snlow| & {\it float} & Lower limit of allowable signal-to-noise in all bands used in the calibration. \\
\verb|color_min| & {\it float array} & Hard lower limits on the colors. Each list entry is ordered to correspond to \verb|colors2calibrate|. In magnitudes.  \\
\verb|color_max| & {\it float array} & Hard upper limits on the colors. Each list entry is ordered to correspond to \verb|colors2calibrate|.  In magnitudes. \\
\verb|mag_min| & {\it float array} & Hard lower limits on the magnitudes. Each list entry is ordered to correspond to the ordered set of all magnitudes appearing in \verb|colors2calibrate|. In magnitudes.  \\
\verb|mag_max| & {\it float array} & Hard upper limits on the magnitudes. Each list entry is ordered to correspond to the ordered set of all magnitudes appearing in \verb|colors2calibrate|.  In magnitudes. \\
\verb|max_locus_dist| & {\it float} & Maximum distance to standard locus line allowable, in magnitudes.  \\
\verb|max_weighted_locus_dist| & {\it float} & Maximum error-weighted distance to standard locus line allowable. In magnitudes.  \\
\verb|magerr_floor| & {\it float} & Error to add to all magnitude errors in quadrature, in magnitudes.  \\

\end{longtable}
\end{center}




\chapter{Color Terms}
\label{sec:colorterms}

\slr\ allows for the use of color terms under a broad but still finite
set of assumptions.  We've attempted to make the assumptions as
flexible as possible, without letting the code become too abstract and
unwieldy.  I'll go over the assumptions here so that you can get this
code to produce better results than you would without using color term
corrections.


\section{The Procedure}
\subsection{Adopt Photometric Calibration Equations}

First, understand that you must adopt a color term convention.  You do
this by adopting photometric calibration equations of the form
\begin{subequations} 
\begin{align}
  \textrm{instrumental mag} & = \textrm{standard mag} + \textrm{zeropoint} + \\
  & (\textrm{color term})\times(\textrm{standard color} -
  \textrm{color constant}).
\end{align}
\end{subequations}
Here the instrumental mag is what is measured after bias subtraction
and flat-fielding, and the standard mag is the standardized measure of
flux that we're ultimately after.  The zeropoints have contributions
from atmospheric extinction and Galactic extinction, from instrumental
sensitivivity, from aperture corrections, and from anything else
additive.  The color term is a constant to be determined, and the
standard color that it multiplies must be chosen.  The value of the
color term constant depends on the standard color that it
multiplies.\footnote{See \citet{bib:slr} for further discussion of the
  form of the photometric and color calibration equations that we use.
}

There is one equation of this form for each magnitude that you are
considering during Stellar Locus Regression.  So for $N$ magnitudes
you must adopt $N$ photometric calibration equations, and $N$
different color terms.  Each color term can multiply a different
standard color.

These equations are entirely standard, so there should be no surprises
here.




\subsection{Measure Your Color Terms}

It is your job to measure the color terms yourself.  Although it is
critical to use color term corrections when calibration data between
different instruments using \slr, we do not provide procedures to do
this for you.  Our goal has been to keep the scope of our \slr\ code
as narrow as possible so that its place within a larger photometric
calibration pipeline is well defined.  Also, we just don't want to
support more code that we have to!

Typically you will measure color terms by matching catalogs of
observed standard stars to a standard catalog, plotting the difference
of instrumental mags and standard mags versus the standard color you
adopted in Step 1, and measuring the slope of a best-fit line.


\subsection{Put the Results in an \slr\ Config File}

The final step is to tell \slr\ what conventions you adopted, and the
values of the color terms you measured.  See \S\ref{sec:config} while
reading the following.

The \slr\ parameter \verb|colortermbands| is a list of characters
signifying the instrumental mags that require color term corrections.
{\it Each band you list here must appear somewhere in
  \verb|colors2calibrate|.}  However it's not necessary to have all
bands appearing in \verb|colors2calibrate| to have an entry in
\verb|colortermbands|, because not all bands need color term
corrections in practice.  So make sure you don't include any extra
bands in the list that just aren't being used in the color calibration
in the first place.

For each entry of \verb|colortermbands| you will need to specify one
value for \verb|colorterms| and \verb|colormult|.  The latter two
configuration parameters are lists that must have the same length as
\verb|colortermbands|, and the lists are ordered.  The colorterms you
measured in Step 2 are placed in \verb|colorterms|, and the standard
color you chose in each passband calibration equation is placed in
\verb|colormult|.  

Here's another important assumption to understand: {\it Each color you
  list in \verb|colormult| must appear in \verb|colors2calibrate|.}
Your adopted standard colors must live in the vector space that you
are calibrating.  They cannot be linear combinations of
\verb|colors2calibrate|.  They must be a subset of
\verb|colors2calibrate|.  While this may be a more restrictive
assumption, we take it to be entirely reasonable under most
circumstances.



\section{An Example}

For example, in \citet{bib:slr} we took data in the $griz$ Sloan
passbands using instruments on the Magellan telescopes.  We noticed
that the color term corrections were significant, so we adopted some
color term equations of the form
\begin{subequations} 
\begin{align}
  g & = g_0 + a_g + E_g + A_g + b_g(g_0-r_0 - \gamma_{gr}) \\
  r & = r_0 + a_r + E_r + A_r + b_r(r_0-i_0 - \gamma_{ri}) \\
  i & = i_0 + a_i + E_i + A_i + b_i(i_0-z_0 - \gamma_{iz}) \\
  z & = z_0 + a_z + E_z + A_z + b_z(i_0-z_0 - \gamma_{iz})
\end{align} 
\end{subequations}
We observed some standard star fields in Stripe 82 and measured the
color terms $b$.  Then for all subsequent observations, we calibrated
our instrumental colors using the same color term values.  We did this
by setting the color term parameters as follows:
\begin{verbatim}
colors2calibrate        gr,ri,iz
colortermbands          g,r,i,z
colorterms              -0.11,-0.01,-0.17,-0.01
colorconst              0.3,0.5,0.7
colormult               gr,ri,iz,iz
\end{verbatim}

In a subsequent step we matched all of our observed stars to the 2MASS
database.  After making a new input colortable that inluded the
$J$-band data from 2MASS, we re-ran \slr\ with the following color
term configuration to calibrate our Magellan $i$-band data:
\begin{verbatim}
colors2calibrate        iz,iJ
colortermbands          i,z
colorterms              -0.17,-0.01 
colorconst              0.5,0.9 
colormult               iz,iz
\end{verbatim}
Note that we had to remove the $g$ and $r$ band entries from the color
term parameters because those bands don't appear in the new list of
\verb|colors2calibrate|.  Also note that the $J$-band needed no color
term correcton.  This is because the $J$ magnitudes were already
calibrated!  In this example, the \slr\ code will not use the second
\verb|colorconst| value because $iJ$ is not one of the
\verb|colormult|'s.



\section{Higher Order Corrections}


It's possible of course to make color-airmass and other higher order
corrections.  The current implementation of \slr\ that we present here
doesn't allow for these, but this is an obvious generalization that we
intend to pursue.








\chapter{Frequently Asked Questions}


\paragraph{Is there documentation of each IDL function?}

Yes, you can generate the html documentation for all IDL function
with:
\begin{verbatim}
IDL> slr_docs
\end{verbatim}
This will make the \slr\ IDL help page
\$SLR\_INSTALL/docs/www/idl\_help.html, which you can open in a web
browser.


\bibliography{slr_manual}
\addcontentsline{toc}{chapter}{Bibliography} 



\input{gfdl}

\end{document}
